home *** CD-ROM | disk | FTP | other *** search
/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / IDE / SUBARTIC / SUB_ARCT / INPUT / DISPATCH.JAV < prev    next >
Encoding:
Text File  |  1996-10-04  |  4.9 KB  |  139 lines
  1. package sub_arctic.input;
  2.  
  3. import sub_arctic.lib.interactor;
  4. import sub_arctic.lib.sub_arctic_error;
  5. import sub_arctic.anim.animatable;
  6. import sub_arctic.anim.trajectory;
  7. import sub_arctic.anim.transition;
  8.  
  9. /**
  10.  * This is the abstract base class for all dispatch agents in all
  11.  * policies.  This API provides methods for reporting whether the agent
  12.  * is interested in a particular type of event, for actually dispatching
  13.  * the event.
  14.  * 
  15.  * @author Scott Hudson
  16.  */
  17. public abstract class dispatch_agent {
  18.  
  19.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  20.  
  21.   /**
  22.    * Construct a dispatch agent.
  23.    */
  24.   public dispatch_agent()
  25.     {
  26.     }
  27.  
  28.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  29.  
  30.   /** 
  31.    * Indicate whether the given event might be dispatchable by this 
  32.    * agent.  Events will not be delivered to the agent unless they pass this
  33.    * test.  Here in the base class we accept everything.
  34.    * 
  35.    * @param event evt the event to be tested for usefulness
  36.    * @return boolean true if the event is one this agent is interested in
  37.    */
  38.   public boolean event_is_useful(event evt)
  39.     {
  40.       /* by default we take anything */
  41.       return true;
  42.     }
  43.  
  44.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  45.  
  46.   /** 
  47.    * Attempt to dispatch an event to an object via this agent.  The
  48.    * event is passed in all cases.  For some policies (e.g.,the positional 
  49.    * policy), an object to dispatch to and a bit of user supplied information
  50.    * (typically this was returned by the object at the time it was picked)
  51.    * can be given.  In other cases null is passed for these to parameters.<P>
  52.    *
  53.    * In addition, for agents which may be passed the same event more than 
  54.    * once (targeted towards different objects), a sequence number is  
  55.    * also passed.  This number is guaranteed to be different for each 
  56.    * different event being dispatched (this allows the agent to know when 
  57.    * to clear its cache or advance within its state machine controller 
  58.    * in certain cases).  <p>
  59.    * 
  60.    * @param event evt the event to dispatch
  61.    * @param Object user_info policy defined user information
  62.    * @param interactor to_obj the object to (possibly)send the event to
  63.    * @param int seq_num the sequence number of this event
  64.    */
  65.   public abstract boolean dispatch_event(
  66.     event      evt, 
  67.     Object     user_info,
  68.     interactor to_obj, 
  69.     int        seq_num);
  70.  
  71.    // had:
  72.    //* @exception general the agent might need to throw any exception
  73.  
  74.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  75.  
  76.   /**
  77.    * This method is called by some policies (most notably the 
  78.    * positional policy) to dispatch events which did not meet the
  79.    * selection criteria of the policy itself. This is necessary
  80.    * for some agents, as they have state machines that depend
  81.    * on knowing when the "next" event occurs, even if that
  82.    * event is not over any object on the interface. <P>
  83.    * 
  84.    * The most common use of this is to remove status displays
  85.    * when the pointer leaves the area of an application via
  86.    * an agent like pointable. <P>
  87.    * 
  88.    * The default implementation of this function is to simply return
  89.    * false.<p>
  90.    *
  91.    * @param event evt the event to dispatch
  92.    * @return boolean true is returned if the event is dispatched
  93.    */
  94.   public boolean dispatch_unused_event(event evt) {
  95.     return false;
  96.   }
  97.  
  98.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  99.  
  100.   /**
  101.    * This method is called by the manager after an event is
  102.    * dispatched on all agents which have registered interest
  103.    * in becoming aware of this fact. You can register for
  104.    * interest using manager.add_to_after_dispatch_list(). <P>
  105.    * 
  106.    * Note that there is no return value from the function,
  107.    * because it is not possible to affect the event -- it
  108.    * has already been dispatched (or not dispatched)
  109.    * when this function is called.<P>
  110.  
  111.    * By default this function does nothing.<P>
  112.    *
  113.    * @param event evt the event which was dispatched (or not)
  114.    * @param boolean dispatched true if the event was handled by some agent
  115.    *
  116.    */
  117.   public void after_dispatch_notify(event evt, boolean dispatched) {
  118.     return;
  119.   }
  120.  
  121.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  122. }
  123. /*=========================== COPYRIGHT NOTICE ===========================
  124.  
  125. This file is part of the subArctic user interface toolkit.
  126.  
  127. Copyright (c) 1996 Scott Hudson and Ian Smith
  128. All rights reserved.
  129.  
  130. The subArctic system is freely available for most uses under the terms
  131. and conditions described in 
  132.   http://www.cc.gatech.edu/gvu/ui/sub_arctic/sub_arctic/doc/usage.html 
  133. and appearing in full in the lib/interactor.java source file.
  134.  
  135. The current release and additional information about this software can be 
  136. found starting at: http://www.cc.gatech.edu/gvu/ui/sub_arctic/
  137.  
  138. ========================================================================*/
  139.